:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: macro
:toclevels: 1
:sectlinks:
:linkattrs:

[[root-controller]]
= Root Controller

toc::[]

== GET /{tenant}/controller/v1/{controllerid}

=== Implementation notes

This base resource can be regularly polled by the controller on the provisioning target or device in order to retrieve actions that need to be executed.
Those are provided as a list of links to give more detailed information about the action.
Links are only available for initial configuration, open actions, or the latest installed action, respectively.
The resource supports Etag based modification checks in order to save traffic.

Note: deployments have to be confirmed in order to move on to the next action.
Cancellations have to be confirmed or rejected.

=== Controller base poll resource

==== Curl

include::{snippets}/rootcontroller/get-controller-base-with-open-deplyoment/curl-request.adoc[]

==== Request URL

include::{snippets}/rootcontroller/get-controller-base-with-open-deplyoment/http-request.adoc[]

==== Request path parameter

include::{snippets}/rootcontroller/get-controller-base-with-open-deplyoment/path-parameters.adoc[]

=== Response (Status 200) with an active deployment

==== Response fields

include::{snippets}/rootcontroller/get-controller-base-with-open-deplyoment/response-fields.adoc[]

==== Response example

include::{snippets}/rootcontroller/get-controller-base-with-open-deplyoment/http-response.adoc[]

=== Response (Status 200) with an active cancellation

==== Response fields

include::{snippets}/rootcontroller/get-controller-base-with-open-deployment-cancellation/response-fields.adoc[]

==== Response example

include::{snippets}/rootcontroller/get-controller-base-with-open-deployment-cancellation/http-response.adoc[]

=== Error responses

|===
| HTTP Status Code | Reason | Response Model

include::../errors/400.adoc[]
include::../errors/401.adoc[]
include::../errors/403_quota.adoc[]
include::../errors/405.adoc[]
include::../errors/406.adoc[]
include::../errors/429.adoc[]
|===


== GET /{tenant}/controller/v1/{controllerid}/cancelAction/{actionId}

=== Implementation notes

The Hawkbit server might cancel an operation, e.g. an unfinished update has a successor. It is up to the provisioning target to decide to accept the cancelation or reject it.

=== Cancel an action

==== Curl

include::{snippets}/rootcontroller/get-controller-cancel-action/curl-request.adoc[]

==== Request URL

include::{snippets}/rootcontroller/get-controller-cancel-action/http-request.adoc[]

==== Request path parameter

include::{snippets}/rootcontroller/get-controller-cancel-action/path-parameters.adoc[]

=== Response (Status 200)

==== Response fields

include::{snippets}/rootcontroller/get-controller-cancel-action/response-fields.adoc[]

==== Response example

include::{snippets}/rootcontroller/get-controller-cancel-action/http-response.adoc[]

=== Error responses

|===
| HTTP Status Code | Reason | Response Model

include::../errors/400.adoc[]
include::../errors/401.adoc[]
include::../errors/403.adoc[]
include::../errors/405.adoc[]
include::../errors/406.adoc[]
include::../errors/429.adoc[]
|===


== POST /{tenant}/controller/v1/{controllerid}/cancelAction/{actionId}/feedback

=== Implementation notes

It is up to the device how much intermediate feedback is provided. However, the action will be kept open until the controller on the device reports a finished (either successful or error) or rejects the action, e.g. the canceled actions have been started already.

=== Feedback channel for cancel actions

==== Curl

include::{snippets}/rootcontroller/post-cancel-action-feedback/curl-request.adoc[]

==== Request URL

include::{snippets}/rootcontroller/post-cancel-action-feedback/http-request.adoc[]

==== Request path parameter

include::{snippets}/rootcontroller/post-cancel-action-feedback/path-parameters.adoc[]

==== Request fields

include::{snippets}/rootcontroller/post-cancel-action-feedback/request-fields.adoc[]

=== Response (Status 200)

=== Error responses

|===
| HTTP Status Code | Reason | Response Model

include::../errors/400.adoc[]
include::../errors/401.adoc[]
include::../errors/403.adoc[]
include::../errors/405.adoc[]
include::../errors/406.adoc[]
include::../errors/409.adoc[]
include::../errors/415.adoc[]
include::../errors/429.adoc[]
|===


== PUT /{tenant}/controller/v1/{controllerid}/configData

=== Implementation notes

The usual behaviour is that when a new device registers at the server it is requested to provide the meta information that will allow the server to identify the device on a hardware level (e.g. hardware revision, mac address, serial number etc.).

=== Response to a requested metadata pull from the provisioning target device.

==== Curl

include::{snippets}/rootcontroller/put-config-data/curl-request.adoc[]

==== Request URL

include::{snippets}/rootcontroller/put-config-data/http-request.adoc[]

==== Request path parameter

include::{snippets}/rootcontroller/put-config-data/path-parameters.adoc[]

==== Request fields

include::{snippets}/rootcontroller/put-config-data/request-fields.adoc[]

=== Response (Status 200)

=== Error responses

|===
| HTTP Status Code | Reason | Response Model

include::../errors/400.adoc[]
include::../errors/401.adoc[]
include::../errors/403.adoc[]
include::../errors/405.adoc[]
include::../errors/406.adoc[]
include::../errors/409.adoc[]
include::../errors/415.adoc[]
include::../errors/429.adoc[]
|===


== GET /{tenant}/controller/v1/{controllerid}/deploymentBase/{actionId}

=== Implementation notes

Core resource for deployment operations. Contains all information necessary in order to execute the operation. 

Keep in mind that the provided download links for the artifacts are generated dynamically by the update server. Host, port and path and not guaranteed to be similar to the provided examples below but will be defined at runtime.

=== Deployment or update action

==== Curl

include::{snippets}/rootcontroller/get-controller-basedeployment-action/curl-request.adoc[]

==== Request URL

include::{snippets}/rootcontroller/get-controller-basedeployment-action/http-request.adoc[]

==== Request path parameter

include::{snippets}/rootcontroller/get-controller-basedeployment-action/path-parameters.adoc[]

==== Request query parameter

include::{snippets}/rootcontroller/get-controller-basedeployment-action/request-parameters.adoc[]

=== Response (Status 200)

==== Response fields

include::{snippets}/rootcontroller/get-controller-basedeployment-action/response-fields.adoc[]

==== Response example

In this case the (optional) query for the last 10 messages, previously provided by the device, are included. Useful if the devices provide state information previously on the feedback channel and won't store it locally.

include::{snippets}/rootcontroller/get-controller-basedeployment-action/http-response.adoc[]


=== Response (Status 200) with a maintenance window defined but not active yet

In addition to the straight forward approach to inform the device to download and install the software in one transaction hawkBit supports the separation of download and installation into separate steps.

This feature is called Maintenance Window where the device is informed to download the software first and then when it enters a defined (maintenance) window the installation triggers follows as in the example above.

==== Response example

Note: artifact details not shown in this example.

include::{snippets}/rootcontroller/get-controller-basedeployment-action-with-maintenance-window/http-response.adoc[]

=== Error responses

|===
| HTTP Status Code | Reason | Response Model

include::../errors/400.adoc[]
include::../errors/401.adoc[]
include::../errors/403.adoc[]
include::../errors/405.adoc[]
include::../errors/406.adoc[]
include::../errors/429.adoc[]
|===


== POST /{tenant}/controller/v1/{controllerid}/deploymentBase/{actionId}/feedback


=== Implementation notes

Feedback channel. It is up to the device how much intermediate feedback is provided. However, the action will be kept open until the controller on the device reports a finished (either successful or error).

=== Feedback channel for update action

==== Curl

include::{snippets}/rootcontroller/post-basedeployment-action-feedback/curl-request.adoc[]

==== Request URL

include::{snippets}/rootcontroller/post-basedeployment-action-feedback/http-request.adoc[]

==== Request path parameter

include::{snippets}/rootcontroller/post-basedeployment-action-feedback/path-parameters.adoc[]

==== Request fields

include::{snippets}/rootcontroller/post-basedeployment-action-feedback/request-fields.adoc[]

=== Response (Status 200)

=== Error responses

|===
| HTTP Status Code | Reason | Response Model

include::../errors/400.adoc[]
include::../errors/401.adoc[]
include::../errors/403.adoc[]
include::../errors/404.adoc[]
include::../errors/405.adoc[]
include::../errors/406.adoc[]
include::../errors/409.adoc[]
include::../errors/410.adoc[]
include::../errors/415.adoc[]
include::../errors/429.adoc[]
|===

== GET /{tenant}/controller/v1/{controllerid}/confirmationBase

=== Implementation notes

Core resource for confirmation related operations. While active actions awaiting confirmation will be referenced, the current auto-confirmation status will be shown. In case auto-confirmation is active, details like the initiator, remark and date of activation (as unix timestamp) will be provided. Reference links to switch the auto-confirmation state are exposed as well.

=== Resource to request confirmation specific information for the controller

==== Curl

include::{snippets}/rootcontroller/get-confirmation-base-with-auto-confirm-active/curl-request.adoc[]

==== Request URL

include::{snippets}/rootcontroller/get-confirmation-base-with-auto-confirm-active/http-request.adoc[]

==== Request path parameter

include::{snippets}/rootcontroller/get-confirmation-base-with-auto-confirm-active/path-parameters.adoc[]

==== Response example (auto-confirmation is active)

The response body in case auto-confirmation is active.

include::{snippets}/rootcontroller/get-confirmation-base-with-auto-confirm-active/http-response.adoc[]

==== Response example (auto-confirmation is not active)

The response body references a link to activate auto-confirmation as well as a link to an open action waiting for confirmation (if present).

include::{snippets}/rootcontroller/get-confirmation-base-with-auto-confirm-deactivated/http-response.adoc[]

=== Error responses

|===
| HTTP Status Code | Reason | Response Model

include::../errors/400.adoc[]
include::../errors/401.adoc[]
include::../errors/403.adoc[]
include::../errors/404.adoc[]
include::../errors/405.adoc[]
include::../errors/406.adoc[]
include::../errors/409.adoc[]
include::../errors/415.adoc[]
include::../errors/429.adoc[]
|===

== POST /{tenant}/controller/v1/{controllerid}/confirmationBase/activateAutoConfirm

=== Implementation notes

The device can use this resource to activate auto-confirmation. As a result all current active as well as future actions will automatically be confirmed by mentioning the initiator as triggered person. Actions will be automatically confirmed, as long as auto-confirmation is active.

=== Interface to activate auto-confirmation for a specific device

==== Curl

include::{snippets}/rootcontroller/activate-auto-confirmation/curl-request.adoc[]

==== Request URL

include::{snippets}/rootcontroller/activate-auto-confirmation/http-request.adoc[]

==== Request path parameter

include::{snippets}/rootcontroller/activate-auto-confirmation/path-parameters.adoc[]

==== Request fields

include::{snippets}/rootcontroller/activate-auto-confirmation/request-fields.adoc[]

=== Response (Status 200)

=== Error responses

|===
| HTTP Status Code | Reason | Response Model

include::../errors/400.adoc[]
include::../errors/401.adoc[]
include::../errors/403.adoc[]
include::../errors/404.adoc[]
include::../errors/405.adoc[]
include::../errors/406.adoc[]
include::../errors/409.adoc[]
include::../errors/415.adoc[]
include::../errors/429.adoc[]
|===

== POST /{tenant}/controller/v1/{controllerid}/confirmationBase/deactivateAutoConfirm

=== Implementation notes

The device can use this resource to deactivate auto-confirmation. All active actions will remain unchanged while all future actions need to be confirmed, before processing with the deployment.

=== Interface to deactivate auto-confirmation for a specific controller

==== Curl

include::{snippets}/rootcontroller/deactivate-auto-confirmation/curl-request.adoc[]

==== Request URL

include::{snippets}/rootcontroller/deactivate-auto-confirmation/http-request.adoc[]

==== Request path parameter

include::{snippets}/rootcontroller/deactivate-auto-confirmation/path-parameters.adoc[]

=== Response (Status 200)

=== Error responses

|===
| HTTP Status Code | Reason | Response Model

include::../errors/400.adoc[]
include::../errors/401.adoc[]
include::../errors/403.adoc[]
include::../errors/404.adoc[]
include::../errors/405.adoc[]
include::../errors/406.adoc[]
include::../errors/409.adoc[]
include::../errors/415.adoc[]
include::../errors/429.adoc[]
|===

== GET /{tenant}/controller/v1/{controllerid}/confirmationBase/{actionId}

=== Implementation notes

Resource to receive information about a pending confirmation.
The response will be of the same format as the deploymentBase operation.
The controller should provide feedback about the confirmation first, before processing the deployment.

Keep in mind that the provided download links for the artifacts are generated dynamically by the update server.
Host, port and path are not guaranteed to be similar to the provided examples below but will be defined at runtime.

=== Confirmation status of an action

==== Curl

include::{snippets}/rootcontroller/get-confirmation-base-action/curl-request.adoc[]

==== Request URL

include::{snippets}/rootcontroller/get-confirmation-base-action/http-request.adoc[]

==== Request path parameter

include::{snippets}/rootcontroller/get-confirmation-base-action/path-parameters.adoc[]

==== Request query parameter

include::{snippets}/rootcontroller/get-confirmation-base-action/request-parameters.adoc[]

=== Response (Status 200)

==== Response fields

include::{snippets}/rootcontroller/get-confirmation-base-action/response-fields.adoc[]

==== Response example

The response body includes the detailed information about the action awaiting confirmation in the same format as for the deploymentBase operation.

include::{snippets}/rootcontroller/get-confirmation-base-action/http-response.adoc[]

=== Error responses

|===
| HTTP Status Code | Reason | Response Model

include::../errors/400.adoc[]
include::../errors/401.adoc[]
include::../errors/403.adoc[]
include::../errors/404_target_action.adoc[]
include::../errors/405.adoc[]
include::../errors/406.adoc[]
include::../errors/429.adoc[]
|===

== POST /{tenant}/controller/v1/{controllerid}/confirmationBase/{actionId}/feedback

=== Implementation notes

The device will use this resource to either confirm or deny an action which is waiting for confirmation. The action will be transferred into the RUNNING state in case the device is confirming it. Afterwards it will be exposed by the deploymentBase.

=== Feedback channel for actions waiting for confirmation

==== Curl

include::{snippets}/rootcontroller/post-confirmation-feedback/curl-request.adoc[]

==== Request URL

include::{snippets}/rootcontroller/post-confirmation-feedback/http-request.adoc[]

==== Request path parameter

include::{snippets}/rootcontroller/post-confirmation-feedback/path-parameters.adoc[]

==== Request fields

include::{snippets}/rootcontroller/post-confirmation-feedback/request-fields.adoc[]

=== Response (Status 200)

=== Error responses

|===
| HTTP Status Code | Reason | Response Model

include::../errors/400.adoc[]
include::../errors/401.adoc[]
include::../errors/403.adoc[]
include::../errors/404_target_action.adoc[]
include::../errors/405.adoc[]
include::../errors/406.adoc[]
include::../errors/409.adoc[]
include::../errors/410.adoc[]
include::../errors/415.adoc[]
include::../errors/429.adoc[]
|===

== GET /{tenant}/controller/v1/{controllerid}/installedBase/{actionId}

=== Implementation notes

Resource to receive information of the previous installation.
Can be used to re-retrieve artifacts of the already finished action, for example in case a re-installation is necessary.
The response will be of the same format as the deploymentBase operation, providing the previous action that has been finished successfully.
As the action is already finished, no further feedback is expected.

Keep in mind that the provided download links for the artifacts are generated dynamically by the update server.
Host, port and path are not guaranteed to be similar to the provided examples below but will be defined at runtime.

=== Previously installed action

==== Curl

include::{snippets}/rootcontroller/get-controller-installed-base-action/curl-request.adoc[]

==== Request URL

include::{snippets}/rootcontroller/get-controller-installed-base-action/http-request.adoc[]

==== Request path parameter

include::{snippets}/rootcontroller/get-controller-installed-base-action/path-parameters.adoc[]

==== Request query parameter

include::{snippets}/rootcontroller/get-controller-installed-base-action/request-parameters.adoc[]

=== Response (Status 200)

==== Response fields

include::{snippets}/rootcontroller/get-controller-installed-base-action/response-fields.adoc[]

==== Response example

The response body includes the detailed operation for the already finished action in the same format as for the deploymentBase operation.

In this case the (optional) query for the last 10 messages, previously provided by the device, are included.

include::{snippets}/rootcontroller/get-controller-installed-base-action/http-response.adoc[]

=== Error responses

|===
| HTTP Status Code | Reason | Response Model

include::../errors/400.adoc[]
include::../errors/401.adoc[]
include::../errors/403.adoc[]
include::../errors/405.adoc[]
include::../errors/406.adoc[]
include::../errors/429.adoc[]
|===

////
== GET /{tenant}/controller/v1/{controllerid}/softwaremodules

=== Implementation notes

Returns all available software modules for a given target

=== Returns software modules of given target

==== Curl

include::{snippets}/rootcontroller/get-software-modules/curl-request.adoc[]

==== Request URL

include::{snippets}/rootcontroller/get-software-modules/http-request.adoc[]

==== Request path parameter

include::{snippets}/rootcontroller/get-software-modules/path-parameters.adoc[]

=== Response (Status 200)

==== Response fields

include::{snippets}/rootcontroller/get-software-modules/response-fields.adoc[]

==== Response example

include::{snippets}/rootcontroller/get-software-modules/http-response.adoc[]

=== Error responses

|===
| HTTP Status Code | Reason | Response Model

include::../errors/400.adoc[]
include::../errors/401.adoc[]
include::../errors/403.adoc[]
include::../errors/405.adoc[]
include::../errors/406.adoc[]
include::../errors/429.adoc[]
|===
////

== GET /{tenant}/controller/v1/{controllerid}/softwaremodules/{softwareModuleId}/artifacts

=== Implementation notes

Returns all artifacts that are assigned to the software module

=== Returns artifacts of given software module

==== Curl

include::{snippets}/rootcontroller/get-software-modules-artifacts/curl-request.adoc[]

==== Request URL

include::{snippets}/rootcontroller/get-software-modules-artifacts/http-request.adoc[]

==== Request path parameter

include::{snippets}/rootcontroller/get-software-modules-artifacts/path-parameters.adoc[]

=== Response (Status 200)

==== Response fields

include::{snippets}/rootcontroller/get-software-modules-artifacts/response-fields.adoc[]

==== Response example

include::{snippets}/rootcontroller/get-software-modules-artifacts/http-response.adoc[]

=== Error responses

|===
| HTTP Status Code | Reason | Response Model

include::../errors/400.adoc[]
include::../errors/401.adoc[]
include::../errors/403.adoc[]
include::../errors/405.adoc[]
include::../errors/406.adoc[]
include::../errors/429.adoc[]
|===


== Additional content

[[error-body]]
=== Error body

include::../errors/error-response-body.adoc[]